/*
*    Qizx/open 3.0 beta
*
* This code is the open-source version of Qizx.
* Copyright (C) 2004-2009 Axyana Software -- All rights reserved.
*
* The contents of this file are subject to the Mozilla Public License 
*  Version 1.1 (the "License"); you may not use this file except in 
*  compliance with the License. You may obtain a copy of the License at
*  http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
*  WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
*  for the specific language governing rights and limitations under the
*  License.
*
* The Initial Developer of the Original Code is Xavier Franc - Axyana Software.
*
*/
using System;
namespace System.Qizx.Api {

    /// <summary> An Item of a Sequence returned by the evaluation of an XQuery Expression.</summary>
    public interface Item {
        /// <summary> Returns the XQuery type of the item.</summary>
        /// <returns> XQuery type of the item
        /// </returns>
        /// <throws>  EvaluationException if access to the item is not possible </throws>
        ItemType ValueType {
            get;
        }

        /// <summary> Gets the item's boolean value.</summary>
        /// <returns> the boolean value. If the item is a node, an attempt to convert
        /// its string value is made.
        /// </returns>
        /// <throws>  EvaluationException if the item cannot be accessed or is not </throws>
        /// <summary>         boolean and not convertible
        /// </summary>
        bool ValueAsBoolean {
            get;

        }
        /// <summary> Gets the item's float value.</summary>
        /// <returns> the float value. If the item is a node, an attempt to convert
        /// its string value is made.
        /// </returns>
        /// <throws>  EvaluationException if the item cannot be accessed or is not </throws>
        /// <summary>         float and not convertible
        /// </summary>
        float ValueAsFloat {
            get;

        }
        /// <summary> Gets the item's double value.</summary>
        /// <returns> the double value. If the item is a node, an attempt to convert
        /// its string value is made.
        /// </returns>
        /// <throws>  EvaluationException if the item cannot be accessed or is not </throws>
        /// <summary>         double and not convertible
        /// </summary>
        double ValueAsDouble {
            get;

        }
        /// <summary> Gets the item's integer value.</summary>
        /// <returns> the long integer value. If the item is a node, an attempt to
        /// convert its string value is made.
        /// </returns>
        /// <throws>  EvaluationException if the item cannot be accessed or is not </throws>
        /// <summary>         integer and not convertible
        /// </summary>
        long ValueAsInteger {
            get;

        }
        /// <summary>
        /// Gets the item's decimal value.
        /// </summary>
        /// <value>The value as decimal.</value>
        /// <returns> the decimal value as a BigDecimal. If the item is a node, an
        /// attempt to convert its string value is made.
        /// </returns>
        /// <throws>  EvaluationException if the item cannot be accessed or is not </throws>
        System.Decimal ValueAsDecimal {
            get;

        }
        /// <summary> Gets the item's String value.</summary>
        /// <returns> the string value
        /// </returns>
        /// <throws>  EvaluationException if the item cannot be accessed </throws>
        string ValueAsString {
            get;

        }
        /// <summary> Gets the item's QName value.</summary>
        /// <returns> the QName value
        /// </returns>
        /// <throws>  EvaluationException if the item cannot be accessed or is not a QName </throws>
        QName ValueAsQName {
            get;

        }
        /// <summary> Converts the item value to a Java object, according to its actual type.
        /// Nodes are converted to w3c DOM nodes.
        /// <p>The precise mapping of XQuery types to Java types is described in
        /// the documentation of <a href='../../../java_binding.html'>Java Binding</a>.</p>
        /// </summary>
        /// <returns> the item converted into a Java object
        /// </returns>
        /// <throws>  QizxException if the item cannot be accessed or if the conversion fails </throws>
        System.Object Object {
            get;

        }

        /// <summary> Tests whether the item is a Node.</summary>
        /// <returns> true if the item is an accessible node
        /// </returns>
        bool IsNode { get; }

        /// <summary> Gets the item's Node value.</summary>
        /// <returns> the item as a Node
        /// </returns>
        /// <throws>  EvaluationException if the item cannot be accessed or is not a Node </throws>
        Node GetNode();

        /// <summary> Streaming export of a Node, in "pull" mode.</summary>
        /// <returns> a XMLPullStream that delivers the contents of the node item.
        /// </returns>
        /// <throws>  EvaluationException if the item cannot be accessed or is not a node </throws>
        XMLPullStream ExportNode();

        /// <summary> Streaming export of a Node in "push" mode. Can use for example
        /// XMLSerializer, PushStreamToSAX, PushStreamToDOM, or a custom adapter to
        /// any other representation.
        /// </summary>
        /// <param name="writer">a push stream output
        /// </param>
        /// <throws>  QizxException if not a node, or not accessible, or </throws>
        /// <summary>         a DataModelException is thrown by the writer.
        /// </summary>
        void Export(XMLPushStream writer);
    }
}